home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / comm / csp101.zip / CSP.DOC next >
Text File  |  1991-04-15  |  10KB  |  331 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                                                                      Page 1
  8.  
  9.  
  10.                                        CSP
  11.                           Preprocessor for SALT Scripts
  12.  
  13.      WHAT IS CSP?
  14.  
  15.      CSP (CS Preprocessor) uses the Microsoft C or QuickC compiler as a
  16.      Telix SALT preprocessor, giving the SALT compiler conditional compile,
  17.      include file, and macro capabilities.
  18.  
  19.      CSP requires Microsoft's QCL.EXE or CL.EXE in one of the directories
  20.      in your PATH.  
  21.  
  22.  
  23.      WHAT DOES IT DO?
  24.  
  25.      Not a whole lot.  It runs a script file (for example FOO.SLT) through
  26.      the Microsoft C compiler (either QCL or CL) with the /P switch to
  27.      create an intermediate file.  The intermediate file is lightly edited,
  28.      then given to the SALT compiler (CS.EXE).  Line references in CS error
  29.      messages are changed from the file and line of the intermediate file
  30.      to the original file and line number.
  31.  
  32.  
  33.      FILES INCLUDED:
  34.  
  35.           CSP.EXE   SALT "preprocessor".
  36.           CSP.DOC   This file.
  37.           CSP.WP5   WordPerfect 5.1 version of this file.
  38.  
  39.  
  40.      HOW DO I USE IT?
  41.  
  42.      The simple syntax is:
  43.  
  44.           CSP sourcefile [outputfile]
  45.  
  46.      Which will preprocess and compile a SALT source file.  SOURCEFILE is
  47.      the name of the script source file.  If no extension is given CSP will
  48.      look for the file with the extension CSP, then SLT.
  49.  
  50.      OUTPUTFILE is the filename (with no extension) CSP is to use when
  51.      creating output files.  If an extension is given it is ignored.  If no
  52.      output name is given then all files are named after the source file.
  53.  
  54.  
  55.      The full syntax is:
  56.  
  57.           CSP [-Q"CMD"] [-PC] [-D MACRO=VALUE]... [-I DIR] [-b]
  58.               [-sstack] sourcefile [outputfile]
  59.  
  60.      switches (which may begin with either '-' or '/') are:
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.                                                                      Page 2
  74.  
  75.      -Q     Use CMD as preprocessor.
  76.      -P     Preprocess only, do not compile.  Creates a .SLI file.
  77.      -C     Tell C preprocessor not to strip comments.
  78.      -D     Tell C preprocessor to define MACRO as VALUE.
  79.      -I     Tell C preprocessor to search DIRECTORY for include files.
  80.      -l     Compile a C-preprocessed SALT file.
  81.      -b     Compress runs of blank lines to one blank line.
  82.      -e     Send C preprocessor error output to standard output.
  83.      -s     Sets the stack size used by the SALT compiler.
  84.  
  85.  
  86.  
  87.      EXPLANATIONS OF OPTIONS:
  88.  
  89.      -Q     Use CMD as preprocessor.
  90.  
  91.      CSP usually uses either QCL or CL as the C preprocessor.  If you have
  92.      another C compiler that can produce compatible preprocessed output /Q
  93.      will force CSP to use it.  If the command requires switches the whole
  94.      command string must be quoted.  For instance if you want CSP to use CL
  95.      instead of QCL (which it would do anyway if it didn't find QCL but I
  96.      can't think of a better example) use:
  97.  
  98.         CSP -Q"CL /P" FOO.SLT
  99.  
  100.  
  101.      -P     Preprocess only, do not compile.  Creates a .SLI file.
  102.  
  103.      CSP will send the file through the C preprocessor and create a CS-
  104.      compilable SLI file, but will not compile it.
  105.  
  106.  
  107.      -C     Tell C preprocessor not to strip comments.
  108.  
  109.      This passes the "/C" switch to the C preprocessor which tells it not
  110.      to strip comments from the source file.
  111.  
  112.  
  113.      -D     Tell C preprocessor to define MACRO as VALUE.
  114.  
  115.      Each -DMACRO=VALUE used passes a "/DMACRO=VALUE" to the C preprocessor
  116.      to define a macro.
  117.  
  118.  
  119.      -l     Compile a C-preprocessed SALT file.
  120.  
  121.      If you have another C compiler that produces Microsoft-compatible
  122.      preprocessor output, you can preprocess the script first then use CSP
  123.      with the -l switch on the output file.  It will not preprocess the
  124.      file, but will compile it with CS and change line references in CS
  125.      error messages.
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.                                                                      Page 3
  140.  
  141.      -b     Compress runs of blank lines to one blank line.
  142.  
  143.      Usually the C preprocessor replaces lines containing preprocessor
  144.      directives and "switched off" code with blank lines.  This option
  145.      replaces multiple blank lines with one blank line, resulting in a more
  146.      presentable SLI file.
  147.  
  148.  
  149.      -e     Send C preprocessor error output to standard output.
  150.  
  151.      This will force the C preprocessor to send all it's messages to the
  152.      standard output, allowing it to be redirected with '>', '>>', and '|'.
  153.  
  154.  
  155.      -s     Sets the stack size used by the SALT compiler.
  156.  
  157.      This option is passed to the SALT compiler to set the stack size of
  158.      the compiled SLC file.
  159.  
  160.      Since you have to have a C compiler to use this I'm assuming you are
  161.      either already familiar with the C preprocessor directives or have
  162.      them documented elsewhere, and they won't be described here. 
  163.      Obviously they work here just as they do in C, since the C compiler is
  164.      doing the preprocessing.  Some notes:
  165.  
  166.      There are a few preprocessor directives that QCL does not remove
  167.      (#pragma for instance), and these are stripped by CSP before the SALT
  168.      compile.  
  169.  
  170.  
  171.      CSP will complain about code like this:
  172.  
  173.           #define FOUR 2+2
  174.           int x=FOUR;
  175.  
  176.      Because neither the C preprocessor nor CS replaces "2+2" with "4", so
  177.      the second line actually evalutes to:
  178.  
  179.           int x=2+2;
  180.  
  181.      and the SALT compiler only allows variable declarations to initialize
  182.      a variable to a constant, not an expression.  If you can't reduce the
  183.      macro to a constant then the the variable must be declared and
  184.      intialized separately:
  185.  
  186.           #define FOUR 2+2
  187.           int x;
  188.           x=FOUR;
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.                                                                      Page 4
  206.  
  207.      Because the C preprocessor strips comments by default, SALT scripts
  208.      that are preprocessed with CSP can contain C-style "/* */" comments,
  209.      as long as the -C switch is not used.
  210.  
  211.  
  212.      DISCLAIMER:
  213.  
  214.      CSP is provided on an "as is" basis without warranty of any kind,
  215.      expressed or implied, including but not limited to the implied
  216.      warranties of merchantability and fitness for a particular purpose.
  217.      The person using the software bears all risk as to the quality and
  218.      performance of the software.  Should the software prove defective, the
  219.      user assumes the entire cost of all necessary repair, servicing, or
  220.      correction.  The author will not be liable for any special,
  221.      incidental, consequential, indirect or  similar damages due to loss of
  222.      data or any other reason, even if the author or an agent of the author
  223.      has been advised of the possibility of such damages.  In no event
  224.      shall the author's liability for any damages ever exceed the price
  225.      paid for the license to use the software, regardless of the form of
  226.      the claim.
  227.  
  228.      REVISION HISTORY:
  229.  
  230.      Version 1.01, April 15:
  231.  
  232.           Added search for files with CSP and SLT extensions.
  233.  
  234.           Filenames and line numbers in CS "warning" messages were not
  235.           being changed to the original file and line number.  Fixed.
  236.  
  237.      Version 1.00, March 16, 1991:  Initial release.
  238.  
  239.  
  240.      ANYTHING ELSE?
  241.  
  242.      There is no charge for private, non-commercial use of CSP (but if you
  243.      send a check anyway it won't go uncashed).  If you use CSP in the
  244.      development of scripts which are sold to others, a $10 registration is
  245.      required.  Comments, suggestions, and requests can be left at:
  246.  
  247.             The Dead of Night BBS
  248.             (703) 644-7667
  249.  
  250.      or mailed to:
  251.  
  252.             Donald Mehrtens
  253.             5923 Minuteman Rd
  254.             Springfield VA 22152
  255.  
  256.      or sent via CompuServe (which I don't check very often) to ID
  257.      72361,1407.
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.                                                                      Page 5
  272.  
  273.      SALT Programmers, HELP!
  274.  
  275.      Is there any way for a script to determine its own name, as DOS ba